HAL MDF IRQ handler and callbacks functions migration

This section provides information about the HAL MDF control functions migration.

Note

  • In HAL1, a single driver handles both MDF and ADF peripherals.

  • In HAL2, the HAL MDF driver has been split into two separate drivers HAL MDF and HAL ADF. For more details, see : MDF specific concept.

  • In HAL1, there are some functions applicable for:

    • Both MDF and ADF peripheral.

    • MDF peripheral only.

    • ADF peripheral only.

  • In the following migration document when the function is applicable for both MDF and ADF the migration describes how to move from HAL1 MDF to HAL2 MDF. The same applies for ADF, example:

  • In HAL1, HAL_MDF_AcqCpltCallback function becomes:

    • HAL_MDF_DFLT_AcqCpltCallback in HAL2 MDF driver.

    • HAL_ADF_DFLT_AcqCpltCallback in HAL2 ADF driver.

  • When the function is applicable only for MDF the migration provides the equivalent for MDF.

  • When the function is applicable only for ADF the migration provides the equivalent for ADF.

Functions applicable for MDF and ADF

HAL MDF acquisition complete callback function

HAL1

HAL2

Function prototype

In HAL1, HAL_MDF_AcqCpltCallback API is triggered when acquisition is complete and the new acquisition value is available for both MDF and ADF: 

HAL_MDF_AcqCpltCallback(MDF_HandleTypeDef *hmdf)

In HAL2, each driver MDF and ADF has its own acquisition complete callback: 

HAL_MDF_DFLT_AcqCpltCallback(hal_mdf_handle_t *hmdf,
                             hal_mdf_block_index_t digital_filter_index)

For ADF the corresponding callback is HAL_ADF_DFLT_AcqCpltCallback.

Example usage 

int32_t acq_value;
void HAL_MDF_AcqCpltCallback(MDF_HandleTypeDef *hmdf)
{
    // Return acquisition MDF value
    HAL_MDF_GetAcqValue(hmdf, &acq_value);
}

int32_t acq_value;
void HAL_MDF_DFLT_AcqCpltCallback(hal_mdf_handle_t *hmdf, hal_mdf_block_index_t digital_filter_index)
{
    // Return acquisition MDF value
    acq_value = HAL_MDF_DFLT_GetAcqValue(hmdf, digital_filter_index);
}

HAL MDF acquisition half complete callback function

HAL1

HAL2

Function prototype

In HAL1, HAL_MDF_AcqHalfCpltCallback API is triggered when acquisition is half complete for both MDF and ADF: 

HAL_MDF_AcqHalfCpltCallback(MDF_HandleTypeDef *hmdf)

In HAL2, each driver MDF and ADF has its own acquisition half complete callback: 

HAL_MDF_DFLT_AcqHalfCpltCallback(hal_mdf_handle_t *hmdf,
                                 hal_mdf_block_index_t digital_filter_index)

For ADF the corresponding callback is HAL_ADF_DFLT_AcqHalfCpltCallback.

Example usage 

void HAL_MDF_AcqHalfCpltCallback(MDF_HandleTypeDef *hmdf)
{
    /* For example, toggle an LED */
    HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
}

void HAL_MDF_AcqHalfCpltCallback(hal_mdf_handle_t *hmdf, hal_mdf_block_index_t digital_filter_index)
{
    /* For example, toggle an LED */
    HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
}

HAL MDF error callback function

HAL1

HAL2

Function prototype

In HAL1, a single error callback API used for both MDF and ADF: 

HAL_MDF_ErrorCallback(MDF_HandleTypeDef *hmdf)

In HAL2, each driver MDF and ADF has its own error callback function:

HAL_MDF_ErrorCallback(hal_mdf_handle_t *hmdf,
                      hal_mdf_block_index_t block_index)

For ADF the corresponding callback is HAL_ADF_ErrorCallback.

Example usage 

void HAL_MDF_ErrorCallback(MDF_HandleTypeDef *hmdf)
{
  /* For example, toggle an LED */
  HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
}

void HAL_MDF_ErrorCallback(hal_mdf_handle_t *hmdf, hal_mdf_block_index_t block_index)
{
  /* For example, toggle an LED */
  HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
}

HAL MDF register callback function

HAL1

HAL2

Function prototype

In HAL1, a single API is provided to register callbacks for both MDF and ADF events: 

HAL_MDF_RegisterCallback(MDF_HandleTypeDef         *hmdf,
                         HAL_MDF_CallbackIDTypeDef CallbackID,
                         pMDF_CallbackTypeDef      pCallback);

In HAL2, separate callbacks are provided for each MDF and ADF event: 

HAL_MDF_DFLT_RegisterAcqCpltCallback(hal_mdf_handle_t *hmdf,
                                     hal_mdf_cb_t p_callback)
HAL_MDF_DFLT_RegisterAcqHalfCpltCallback(hal_mdf_handle_t *hmdf,
                                         hal_mdf_cb_t p_callback)
HAL_MDF_RegisterErrorCallback(hal_mdf_handle_t *hmdf,
                              hal_mdf_cb_t p_callback)

For ADF the corresponding register callbacks are HAL_ADF_DFLT_RegisterAcqCpltCallback, HAL_ADF_DFLT_RegisterAcqHalfCpltCallback, HAL_ADF_RegisterErrorCallback, and HAL_ADF_SAD_RegisterSoundActivityCallback.

Example usage 

HAL_MDF_RegisterCallback(&hmdf, HAL_MDF_ACQ_COMPLETE_CB_ID, USER_MDF_AcqCplt_Callback)
HAL_MDF_RegisterCallback(&hmdf, HAL_MDF_ACQ_HALFCOMPLETE_CB_ID, USER_MDF_AcqHalfCplt_Callback)
HAL_MDF_RegisterCallback(&hmdf, HAL_MDF_ERROR_CB_ID, USER_MDF_Error_Callback)

HAL_MDF_DFLT_RegisterAcqCpltCallback(&hmdf, USER_MDF_AcqCplt_Callback)
HAL_MDF_DFLT_RegisterAcqHalfCpltCallback(&hmdf, USER_MDF_AcqHalfCplt_Callback)
HAL_MDF_RegisterErrorCallback(&hmdf, USER_MDF_Error_Callback)

HAL MDF unregister callback function

HAL1

HAL2

Function prototype 

HAL_MDF_UnRegisterCallback(MDF_HandleTypeDef         *hmdf,
                           HAL_MDF_CallbackIDTypeDef CallbackID)

Unregister callback functions are no longer provided. Use instead register callback functions with the default weak callback.

Example usage 

HAL_MDF_UnRegisterCallback(&hmdf, HAL_MDF_ACQ_COMPLETE_CB_ID)
HAL_MDF_UnRegisterCallback(&hmdf, HAL_MDF_ACQ_HALFCOMPLETE_CB_ID)
HAL_MDF_UnRegisterCallback(&hmdf, HAL_MDF_ERROR_CB_ID)
HAL_MDF_UnRegisterCallback(&hadf, HAL_MDF_SAD_CB_ID)

HAL_MDF_DFLT_RegisterAcqCpltCallback(&hmdf, HAL_MDF_DFLT_AcqCpltCallback)
HAL_MDF_DFLT_RegisterAcqHalfCpltCallback(&hmdf, HAL_MDF_DFLT_AcqHalfCpltCallback)
HAL_MDF_RegisterErrorCallback(&hmdf, HAL_MDF_ErrorCallback)
HAL_ADF_SAD_RegisterSoundActivityCallback(&hadf, HAL_ADF_SAD_SoundActivityCallback)

HAL MDF IRQ handler function

HAL1

HAL2

In HAL1, a single IRQ handler function is provided to handle both MDF and ADF: 

HAL_MDF_IRQHandler()

In HAL2, each driver MDF and ADF has its own IRQ handler: 

HAL_MDF_IRQHandler(hal_mdf_handle_t *hmdf, hal_mdf_block_index_t block_index)
HAL_ADF_IRQHandler(hal_adf_handle_t *hadf, hal_adf_block_index_t block_index)

Functions applicable for MDF only

HAL MDF out of limit callback function

HAL1

HAL2

Function prototype

In HAL1, HAL_MDF_OldCallback API is triggered when out of limit is detected for MDF only (not used with ADF): 

HAL_MDF_OldCallback(MDF_HandleTypeDef *hmdf,
                    uint32_t ThresholdInfo)

In HAL2, use HAL_MDF_OLD_Callback API to inform the user that out of limit event is detected: 

HAL_MDF_OLD_Callback(hal_mdf_handle_t *hmdf,
                     hal_mdf_block_index_t out_of_limit_detector_index,
                     hal_mdf_old_threshold_info_t threshold_info)

Example usage 

void HAL_MDF_OldCallback(MDF_HandleTypeDef *hmdf, uint32_t ThresholdInfo)
{
  if (ThresholdInfo == MDF_OLD_LOW_THRESHOLD) {
    // value below low threshold
  } else if (ThresholdInfo == MDF_OLD_HIGH_THRESHOLD) {
    // value above high threshold
  } else {
    // returned to the range
  }
}

void HAL_MDF_OLD_Callback(hal_mdf_handle_t *hmdf,
                          hal_mdf_block_index_t out_of_limit_detector_index,
                          hal_mdf_old_threshold_info_t threshold_info)
{
  if (threshold_info == HAL_MDF_OLD_THRESHOLD_LOW) {
    // value below low threshold
  } else if (threshold_info == HAL_MDF_OLD_THRESHOLD_HIGH) {
    // value above high threshold
  } else {
    // returned to the range
  }
}

HAL MDF out of limit register callback function

HAL1

HAL2

Function prototype

In HAL1, HAL_MDF_RegisterOldCallback function is provided to register MDF out of limit detection callback (not used with ADF): 

HAL_MDF_RegisterOldCallback(MDF_HandleTypeDef       *hmdf,
                            pMDF_OldCallbackTypeDef pCallback)

In HAL2, use HAL_MDF_OLD_RegisterCallback function to register MDF out of limit detection callback: 

HAL_MDF_OLD_RegisterCallback(hal_mdf_handle_t *hmdf,
                             hal_mdf_old_cb_t p_callback)

Example usage 

HAL_MDF_RegisterOldCallback(&hmdf, USER_MDF_Old_Callback)

HAL_MDF_OLD_RegisterCallback(&hmdf, USER_MDF_OLD_Callback)

HAL MDF out of limit unregister callback function

HAL1

HAL2

Function prototype 

HAL_MDF_UnRegisterOldCallback(MDF_HandleTypeDef       *hmdf,
                              pMDF_OldCallbackTypeDef pCallback)

Unregister callback functions are no longer provided. Use instead register callback functions with the default weak callback.

Example usage 

HAL_MDF_UnRegisterOldCallback(&hmdf, HAL_MDF_OLD_CB_ID)

HAL_MDF_OLD_RegisterCallback(&hmdf, HAL_MDF_OLD_Callback)

Functions applicable for ADF only

HAL MDF sound level callback function

HAL1

HAL2

Function prototype

In HAL1, HAL_MDF_SndLvlCallback API is triggered when sound level and ambient noise values are ready for ADF only (not used with MDF): 

HAL_MDF_SndLvlCallback(MDF_HandleTypeDef *hmdf,
                       uint32_t SoundLevel,
                       uint32_t AmbientNoise)

In HAL2, HAL_ADF_SAD_SoundLevelCallback API is provided to inform the user that sound level and ambient noise values are ready: 

HAL_ADF_SAD_SoundLevelCallback(hal_adf_handle_t *hadf,
                               hal_adf_block_index_t sound_activity_detector_index)

Example usage 

void HAL_MDF_SndLvlCallback(MDF_HandleTypeDef *hmdf, uint32_t SoundLevel, uint32_t AmbientNoise)
{
    /* the sound level and ambient noise values are available in SoundLevel
       and AmbientNoise variables and it can be used by the user */
}

uint32_t sound_level;
uint32_t ambient_noise;
void HAL_ADF_SAD_SoundLevelCallback(hal_adf_handle_t *hadf, hal_adf_block_index_t sound_activity_detector_index)
{
    /* The HAL_ADF_SAD_SoundLevelCallback informs the user that sound level and ambient noise values
       are ready and can be retrieved by calling the HAL_ADF_SAD_GetSoundAndAmbientNoiseLevels function */
    HAL_ADF_SAD_GetSoundAndAmbientNoiseLevels(hadf, sound_activity_detector_index, &sound_level, &ambient_noise);
}

HAL MDF sound activity callback function

HAL1

HAL2

Function prototype

In HAL1, HAL_MDF_SadCallback API is triggered when sound activity is detected for ADF only (not used with MDF): 

HAL_MDF_SadCallback(MDF_HandleTypeDef *hmdf)

In HAL2, HAL_ADF_SAD_SoundActivityCallback API is provided to inform the user that sound activity is detected: 

HAL_ADF_SAD_SoundActivityCallback(hal_adf_handle_t *hadf,
                                  hal_adf_block_index_t sound_activity_detector_index)

Example usage 

void HAL_MDF_SadCallback(MDF_HandleTypeDef *hmdf)
{
    /* For example, toggle an LED */
    HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
}

void HAL_ADF_SAD_SoundActivityCallback(hal_adf_handle_t *hadf, hal_adf_block_index_t sound_activity_detector_index)
{
    /* For example, toggle an LED */
    HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
}

HAL MDF sound level register callback function

HAL1

HAL2

Function prototype

In HAL1, HAL_MDF_RegisterSndLvlCallback function is provided to register ADF sound level callback (not used with MDF): 

HAL_MDF_RegisterSndLvlCallback(MDF_HandleTypeDef          *hmdf,
                               pMDF_SndLvlCallbackTypeDef pCallback)

In HAL2, use HAL_ADF_SAD_RegisterSoundLevelCallback function to register ADF sound level callback: 

HAL_ADF_SAD_RegisterSoundLevelCallback(hal_adf_handle_t *hadf,
                                       hal_adf_cb_t p_callback)

Example usage 

HAL_MDF_RegisterSndLvlCallback(&hadf, USER_ADF_SndLvl_Callback)

HAL_ADF_SAD_RegisterSoundLevelCallback(&hadf, USER_ADF_SndLvl_Callback)

HAL MDF sound level unregister callback function

HAL1

HAL2

Function prototype 

HAL_MDF_UnRegisterSndLvlCallback(MDF_HandleTypeDef    *hmdf,
                                 pMDF_SndLvlCallbackTypeDef pCallback)

Unregister callback functions are no longer provided. Use instead register callback functions with the default weak callback.

Example usage 

HAL_MDF_UnRegisterSndLvlCallback(&hadf, HAL_MDF_SNDLVL_CB_ID)

HAL_ADF_SAD_RegisterSoundLevelCallback(&hadf, HAL_ADF_SAD_SoundLevelCallback)

HAL MDF callback pointers

HAL1

HAL2

pMDF_CallbackTypeDef()

For MDF driver use instead: hal_mdf_cb_t()

For ADF driver use instead: hal_adf_cb_t()

pMDF_OldCallbackTypeDef()

hal_mdf_old_cb_t()

pMDF_SndLvlCallbackTypeDef()

No specific pointer type for sound level event in HAL2; use hal_adf_cb_t() instead.